SetThreadState

SetThreadState
Header:	Threads.h		Carbon status:	Supported

Changes the state of any thread.

OSErr SetThreadState (
    ThreadID threadToSet, 
    ThreadState newState, 
    ThreadID suggestedThread
);

threadToSet: The thread ID of the thread whose state is to be changed.
newState: The new state for the thread. You can specify ready to execute (kThreadReadyState), stopped (kStoppedThreadState), or executing (kRunningThreadState).
suggestedThread: The thread ID of the next thread to run. You specify this thread if you are changing the state of the currently executing thread to stopped or ready to run. Pass kNoThreadID if you do not want to specify a particular thread to run next. In this case, the Thread Manager schedules the next available thread to run.

function result: A result code.

DISCUSSION

The effect of SetThreadState depends on whether the thread you specify for changing is the currently executing thread or another thread. If you specify the current thread and thus change the state to stopped or ready, SetThreadState invokes the Thread Manager scheduling mechanism. The current thread relinquishes control (it is put in the state you specify, stopped or ready) and the Thread Manager schedules the thread that you specify with the suggestedThread parameter. If this thread is unavailable for running, or if you passed kNoThreadID, the Thread Manager schedules the next available thread.

If you change the state of the current thread to ready, the Thread Manager suspends it awaiting availability of the CPU. When it is rescheduled, SetThreadState regains control and returns to the function that called it.

If you have installed a custom scheduler, the Thread Manager passes it the thread ID of the suspended thread.

If you specify a thread other than the currently executing thread, no rescheduling occurs. If you change the state from ready to stopped, the thread is removed from the scheduling queue. The Thread Manager does not schedule this thread for execution again until you change its state to ready. On the other hand, if you change the state from stopped to ready, you have in effect put the thread in the scheduling queue, and the Thread Manager gives it CPU time as soon as it reaches the top of the scheduling queue.

Threads must yield in the CPU addressing mode (24-bit or 32-bit) in which the application was launched.

To obtain the state of any thread, use the GetThreadState function.

To relinquish control to the next available thread, use the YieldToAnyThread function. To relinquish control to a specific thread, use the YieldToThread function.

To set the state of the current thread before it exits a critical section of code, use the SetThreadStateEndCritical function.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when ThreadsLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by ThreadsLib 1.0 and later.